docs(objectql): correct MetadataFacade's class docblock — it is not the installed 'metadata' kernel service - #14525
Merged
Conversation
…file's own true statement
The class docblock claimed the facade is "Registered as the 'metadata' kernel
service"; sixty lines later, registerObjectBothPlaces' header states the
opposite and is the true one. Re-measured on this tree: the only non-test
ctx.registerService('metadata', ...) site registers MetadataPlugin's manager,
the kernel's core-fallback pre-injection registers createMemoryMetadata, and
new MetadataFacade(...) appears nowhere outside tests.
Rewrite the class docblock to say what the class is (an injectable
IMetadataService over a SchemaRegistry, exported for downstream hosts) and
what it is not (installed into the 'metadata' slot by anything here), and
bind the two statements so the next reader cannot pick the wrong one. Prose
only; no registration and no behaviour change.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68
…rection The class docblock reaches the published declaration chunk that dist/index.d.ts and dist/core.d.ts re-export MetadataFacade from, so the correction is a reader-visible change in the published package. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68
Contributor
📓 Docs Drift Check
What this run could not see
Coarse fallback — 16 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): |
github-actions
Bot
added
documentation
os-musk
marked this pull request as ready for review
September 2, 2026 13:08
Collaborator
Author
|
Landing provenance (engine execution seat,
Generated by Claude Code |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #14019
Prose only. One TSDoc block in
packages/objectql/src/metadata-facade.ts, plus its changeset.What was wrong
The class docblock said
MetadataFacadeis "Registered as the 'metadata' kernel service".Sixty lines down the same file,
registerObjectBothPlaces' header says the opposite —nothing installs a
MetadataFacadeinto that slot — and the second statement is the trueone. The false half is load-bearing: a reader grepping for who fills the
metadataslotlands on the class docblock first and stops there.
The docblock now says what the class is (an injectable
IMetadataServiceover aSchemaRegistry, exported from this package's root andcoreentrypoints for a downstreamhost that chooses to install it) and what it is not (installed into the
'metadata'slot by anything in this repository), names the two real fillers, and points at the
registerObjectBothPlacesheader so the two statements cannot be read apart.Premise re-verified on this branch, not taken from the card
329608eb0git grep -n "registerService('metadata'" -- packagespackages/metadata/src/plugin.ts:365, registeringthis.managergit grep -c "registerService(" -- packagespackages/core/src/kernel.ts:5) — the pattern engine does see this tree, so a zero above would have meant somethingpackages/core/src/kernel.ts:270(preInjectCoreFallbacks) and:303(validateSystemRequirements) registerCORE_FALLBACK_FACTORIES.metadata, which iscreateMemoryMetadata(packages/core/src/fallbacks/index.ts:41)git grep -n "new MetadataFacade" -- packagesOne drift from the card's own text, recorded rather than silently corrected: the manager
registration is at
plugin.ts:365here, not:353. Substance unchanged.The
dist/*.d.tsmeasurement (PM assumption 2 — CONFIRMED)Built with
pnpm --filter '@objectstack/objectql^...' build && pnpm --filter @objectstack/objectql build(under the shared verify lock;
VERDICT command-exit 0), then grepped the emitted declarations:dist/util-BKgrGIUi.d.ts, 0 indist/index.d.ts/dist/core.d.ts.can give every kernel its own…"): 1 hit, same file, 0 in the other two. So the zeroes
above are about which file carries the declaration, not about TSDoc being stripped.
dist/tree.dist/index.d.tsanddist/core.d.tsboth re-exportM as MetadataFacadefrom
./util-BKgrGIUi.js,typesisdist/index.d.ts, andfilesis["dist", …].⇒ The class docblock does ship to consumers — it is what an editor hover shows on an
imported
MetadataFacade— so this is a reader-visible change in the published package anda
@objectstack/objectql: patchchangeset is owed. It is in the diff; noskip-changesetlabel is claimed.
Clause-②: no, read from this diff
git diffover the source file: 18 added / 5 removed lines, every one a*TSDoccomment-body line — the complement grep (changed lines that are not comment-body lines)
returns nothing. No emitted runtime byte, no public type, no accept/reject behaviour, no
gate move. No ablation is owed for a comment-only diff, and none was run.
Scope
No registration change. Installing a
MetadataFacadeinto themetadataslot is behaviourand belongs to #13331's solution space (a
priority:p0card, mentioned here only as thecard whose premise this docblock likely produced — nothing about it is claimed or changed
by this PR).
The
registerObjectBothPlacesheader at:134was not edited: it already carries thetrue statement, and the rewritten class docblock now agrees with it and points at it, which
is the one-voice requirement the triage set. Editing it too would have been churn on a
sentence that was never wrong.
Verification (all at
329608eb0, the final commit)node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands→ 30 commands.All 30 run; 27 exit 0, and 3 report NOT MEASURED in their own words rather than a red:
check-test-completeness.mjs(exit 3 — needs a savedturbo run testlog; "It is not a red,and there is nothing here to fix"),
scripts/pm/check-half-states.mjs(exit 3 — needsrepo-scoped REST egress this container does not have), and
check:dual-build-cjs-loads(exit 3 — "PREREQUISITE NOT MET … Run
pnpm buildfirst"; only objectql's closure is builtlocally, CI builds the workspace).
pnpm lintwhole repo, exit 0 in 74s (no narrowingneeded),
pnpm check:nul-bytesexit 0 (7922 files scanned),pnpm check:error-status-conformanceexit 0,
pnpm --filter @objectstack/objectql typecheckexit 0 (source, scripts, and thetest-layer project — 44 test files).
vitest runwas not run locally. Grounds: everychanged line is inside a TSDoc block (proof above), no test or gate reads this file as text
(
git grepfor the removed sentence returns nothing tree-wide), the package builds andtype-checks green, and CI's Test Core runs the suite on this PR. The box was also running
another seat's full objectql suite under the shared lock at the time.
The derivation printed a STALE TREE warning (this branch is 4 commits behind
origin/main,one family file changed in that range:
scripts/measure-durability-swallow-family.mjs).Inspected: that diff only repoints the durability self-test's "dark control" example file and
rewrites its prose — it does not change which families my two paths map to, and re-deriving
after
git fetch origin mainproduced a byte-identical command list.🤖 Generated with Claude Code
https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68
Generated by Claude Code